跳到主要内容

Skills 体系与 Plugin 架构

Anthropic 2025 年推出的 Skills 是 Claude Code、Claude Desktop 当前的核心能力机制。它和 Tools、Sub-agents、MCP 一起，构成了 AI 应用能力的"四件套"。这一篇把这套体系彻底讲清楚。

学前说明​

如果你只用过 Claude API 或 ChatGPT，可能没接触过 Skills。但如果你用过 Claude Code、Cursor、Cline，你已经在用 Skills（只是可能没意识到）。

Skills 解决的是这个问题：当 AI 助手要干 100 种不同任务时，怎么组织能力让它精确选用。

不是这样：

  • 把所有能力都堆在一个 system prompt 里（太长、互相干扰）
  • 每次都让 AI 从零开始想（重复劳动、不一致）
  • 完全靠 Tools（Tools 是原子操作，Skills 是任务模板）

而是这样：

  • 把可复用的"任务知识"封装成 Skill
  • AI 根据当前任务自动加载相关 Skill
  • Skill 内部可以调用 Tools、MCP Server、Sub-agent

学习目标​

  • 理解 Skills 的本质（vs Tools、vs Sub-agents、vs MCP）
  • 掌握 SKILL.md 规范，能写出可触发的 Skill
  • 设计 Skill 与 MCP Server 的集成模式
  • 建立 Plugin 架构（Skills + MCP + Tools 三位一体）
  • 团队级 Skills 治理与 marketplace
  • 从真实 Skills 案例反推设计原则

与现有知识的衔接​

  • 5-7 MCP 与 Tool Use：Tools 是原子能力，本篇 Skills 是任务级能力
  • 5-8 Coding Agent：Coding Agent 大量使用 Skills
  • 6-9 AI 编辑器深度定制：Skills 是定制 IDE Agent 的核心机制

第一章：Skills 是什么​

1.1 定义​

Skill = 一份描述"如何完成某类任务"的 Markdown 文件 + 可选的辅助资源。

最小的 Skill 只有一个 SKILL.md：

---
name: code-review
description: 审查代码 PR 的质量、风格、安全性
---

# 代码审查 Skill

当用户请求审查 PR、代码或 diff 时使用。

## 执行步骤

1. 读取 git diff
2. 按以下维度检查：
   - 类型安全（无 any、ts-ignore）
   - 命名规范
   - 错误处理
   - 测试覆盖
3. 输出结构化报告

## 输出格式

按严重程度分类：
- 严重问题（必须修）
- 建议改进（应该修）
- 可选优化（可以修）

LLM 看到这个文件，就"学会"了如何做 code review，下次用户说"帮我 review 这个 PR"时会自动应用。

1.2 Skills vs Tools vs Sub-agents vs MCP​

四个相邻概念的本质区别：

概念是什么调用者粒度状态
Tool一个函数调用LLM原子（一次操作）无状态
MCP Server一组工具 + 资源LLM一组相关原子有状态（连接）
Skill任务模板（指令 + 步骤 + 资源）LLM 自动加载任务级（一类工作）无状态
Sub-agent独立 Agent（带自己的上下文）主 Agent 委派子任务（独立目标）独立上下文

举一个具体例子帮助理解：

任务：把这个 React 组件迁移到 Vue

Tools 提供原子能力：
  - read_file
  - write_file
  - run_command

MCP Server 提供一组相关能力：
  - github MCP（PR、issue、commit）

Skill 提供任务知识：
  "react-to-vue-migration" Skill
  - 怎么映射生命周期（useEffect → onMounted）
  - 怎么转换 JSX → template
  - 常见陷阱和测试方法

Sub-agent 用于独立子任务：
  "test-runner" sub-agent
  - 在隔离环境跑测试
  - 不污染主对话上下文

1.3 Skills 的工程价值​

1. 知识可复用

把"怎么做 X"的方法论从 Prompt 中抽离，团队共享、版本管理。

2. 上下文可控

Skills 按需加载，不污染主上下文。100 个 Skill 不会让上下文爆炸——只有相关的会被激活。

3. 触发可预测

通过 description 字段精确控制 Skill 何时被触发，比靠模型"自己想"更可靠。

4. 组合可扩展

Skill 可以引用其他 Skill、调用 Tools、使用 MCP，是高阶组合单元。

第二章：SKILL.md 规范详解​

2.1 完整结构​

---
# Frontmatter（YAML 元数据）
name: my-skill                    # 必填：唯一标识，kebab-case
description: 一句话描述能力        # 必填：用于触发匹配，要写好
version: 1.0.0                   # 可选：语义化版本
author: team-name                # 可选
allowed-tools:                   # 可选：限制此 Skill 能用的工具
  - read_file
  - run_command
required-mcp:                    # 可选：依赖的 MCP Server
  - github
---

# Skill 标题

## 何时使用（必须有）

明确描述触发场景。LLM 据此判断是否激活。

## 不要使用的场景

明确列出反例，避免误触发。

## 执行步骤

按顺序的操作清单。

## 关键约束

必须遵守的规则。

## 输出格式

期望的输出结构。

## 参考资源

- 链接到其他文件
- 引用其他 Skill

2.2 关键字段：description​

description 是 Skill 触发的核心。写好它比 Skill 内容本身更重要。

反例​

description: A skill for code review
# ❌ 太泛，无法判断何时用

正例​

description: |
  审查代码 PR、diff 或单个文件的质量问题。
  适用：用户说"review 这段代码"、"检查 PR"、"看看这个改动有没有问题"
  不适用：写新代码、调试问题、解释代码

LLM 看到 description，会判断当前用户请求是否匹配。所以 description 要：

  • 明确正向场景（适用）
  • 明确反向场景（不适用）
  • 用用户实际会说的语言（不是技术黑话）

2.3 何时使用章节​

正文第一节通常是 "何时使用"，这是 description 的扩展版：

## 何时使用此 Skill

**触发关键词**
- "review"、"审查"、"check"
- "PR"、"diff"、"改动"
- "代码质量"、"code quality"

**典型场景**
- 用户分享了 PR 链接
- 用户粘贴了一段 diff
- 用户问"这段代码有问题吗"

**不要使用**
- 用户在写新代码 → 用 implement-feature skill
- 用户在 debug bug → 用 debug-issue skill
- 用户问代码原理 → 直接对话回答

2.4 步骤的写法​

不要写得太抽象，要具体到"AI 能直接执行"：

## 执行步骤

### 1. 读取改动

\```bash
git diff main..HEAD
\```

如果用户提供的是 PR 链接，先用 GitHub MCP 拉取 diff。

### 2. 静态检查

按以下顺序：
- 跑 `npm run typecheck`，记录所有错误
- 跑 `npm run lint`，记录所有 error 级别问题
- 跑 `npm run test`，确认改动没破坏现有测试

### 3. 人工审查维度

- **类型安全**：搜索 `\\bany\\b`、`@ts-ignore`、`as any`
- **错误处理**：搜索 `catch(.*){}`、未 await 的 Promise
- **命名**：对照项目 CLAUDE.md 里的命名规范
- **测试**：新增逻辑必须有对应测试

### 4. 输出报告

按下方格式生成。

2.5 输出格式约束​

明确的输出格式让 Skill 可被工具消费：

## 输出格式

\```json
{
  "summary": "本次 review 的总结（2-3 句话）",
  "issues": [
    {
      "severity": "critical" | "warning" | "info",
      "file": "src/foo.ts",
      "line": 42,
      "message": "具体问题描述",
      "suggestion": "建议如何修改"
    }
  ],
  "recommendation": "approve" | "request_changes" | "comment"
}
\```

第三章：Skills 自动触发机制​

3.1 触发的两阶段​

第一阶段（Description 匹配）只加载 description（每个 100 字左右），轻量。 第二阶段（Skill 加载）才把完整 SKILL.md 加入上下文，按需进行。

3.2 多 Skill 共存的场景​

100 个 Skill 是常见情况，触发要做到：

  • 正确激活：用户意图匹配的 Skill 被加载
  • 避免误激活：不相关的 Skill 不进上下文
  • 多 Skill 协同：复杂任务可能需要多个 Skill
// 系统加载逻辑（伪代码）
async function loadRelevantSkills(userMessage: string, allSkills: Skill[]) {
  // 1. 用 LLM 判断匹配（用 Haiku 这种便宜模型）
  const matches = await llm.classify({
    model: 'claude-haiku',
    input: userMessage,
    options: allSkills.map(s => ({
      id: s.name,
      description: s.description
    })),
    multipleChoice: true,  // 允许多 Skill 匹配
  });
  
  // 2. 加载匹配的 Skill 全文
  const loadedSkills = matches.map(m => 
    allSkills.find(s => s.name === m.id)
  );
  
  // 3. 注入到主对话上下文
  return loadedSkills.map(s => s.fullContent);
}

3.3 触发的反模式​

反模式 1：description 写得太通用

description: Helps with coding tasks
# 几乎所有 coding 请求都会触发，污染上下文

反模式 2：Skill 过于细粒度

把"添加 import 语句"做成一个 Skill 是过度。Skill 应该是任务级，不是步骤级。

反模式 3：Skill 互相冲突

两个 Skill 都说"用于代码 review"，LLM 不知道用哪个。要么合并，要么明确区分场景。

第四章：自定义 Skill 开发​

4.1 一个真实例子：组件创建 Skill​

---
name: create-react-component
description: |
  创建新的 React 组件，遵循项目规范。
  适用：用户说"新建组件 X"、"创建一个 X 组件"、"add a X component"
  不适用：修改现有组件、删除组件
allowed-tools:
  - read_file
  - write_file
  - run_command
---

# 创建 React 组件 Skill

## 何时使用

用户明确要求创建一个新的 React 组件。

## 执行步骤

### 1. 确认信息

如果用户没说清，问：
- 组件名（PascalCase）
- 大致功能
- 是否需要 props
- 放在哪个目录（默认 `src/components/`）

### 2. 创建文件结构

\```
src/components/[ComponentName]/
├── [ComponentName].tsx
├── [ComponentName].test.tsx
├── [ComponentName].stories.tsx
└── index.ts
\```

### 3. 组件模板

参考 `src/components/Button/` 的写法。关键约定：

\```typescript
import { type FC } from 'react';
import styles from './ComponentName.module.css';

export interface ComponentNameProps {
  // ...
}

export const ComponentName: FC<ComponentNameProps> = ({ ... }) => {
  return <div className={styles.root}>...</div>;
};
\```

### 4. 测试模板

每个组件至少要有：
- 渲染测试
- props 变化测试
- 用户交互测试（如果有）

### 5. 注册到 index

修改 `src/components/index.ts`，添加：
\```typescript
export { ComponentName } from './ComponentName';
export type { ComponentNameProps } from './ComponentName';
\```

### 6. 验证

\```bash
npm run typecheck
npm run lint
npm run test -- ComponentName
\```

## 必须遵守

- 组件名 PascalCase
- props 接口名 ComponentNameProps
- 默认导出 + 命名导出都要
- 必须支持 className 透传
- 必须有 displayName

## 输出

完成后报告：
- 创建了哪些文件
- typecheck/lint/test 是否通过
- 任何需要用户决定的待定项

4.2 Skill 文件组织​

复杂 Skill 可能需要辅助文件：

.claude/skills/
└── create-react-component/
    ├── SKILL.md              # 主文件
    ├── templates/
    │   ├── component.tsx.tmpl
    │   ├── test.tsx.tmpl
    │   └── stories.tsx.tmpl
    └── examples/
        └── Button/           # 参考实现

SKILL.md 中可以引用这些资源：

## 模板

参考 `templates/component.tsx.tmpl` 作为新组件的起点。
参考 `examples/Button/` 看完整的实现示例。

4.3 Skill 设计原则​

五条黄金原则

1. 任务级，不是步骤级

✅ "代码审查 Skill"
❌ "添加 import Skill"

2. 单一职责

一个 Skill 只解决一类任务。"通用助手 Skill" 是反模式。

3. 描述先行

写 Skill 前先把 description 想清楚——能不能用一句话说明白何时用。

4. 包含反例

明确说"不要用于"什么场景。

5. 验证清单

每个 Skill 应该有"完成判定"标准。

第五章：Skill 与 MCP 集成​

5.1 谁负责什么​

Skill = 任务知识（怎么做）
MCP Server = 工具能力（能做什么）

Skill 调用 MCP 工具完成任务。

例如，"GitHub PR Review Skill" 调用 "GitHub MCP Server" 的工具：

---
name: github-pr-review
description: 审查 GitHub PR
required-mcp:
  - github
---

## 执行步骤

### 1. 获取 PR 信息

调用 `github.get_pr` 工具，参数：
- owner: 从 URL 提取
- repo: 从 URL 提取
- pr_number: 从 URL 提取

### 2. 获取改动文件

调用 `github.list_pr_files` 工具。

### 3. 分析每个文件

逐个调用 `github.get_file_content` 读取，按 review 维度检查。

### 4. 提交评论

调用 `github.create_pr_review_comment` 添加行级评论。

5.2 声明依赖​

在 frontmatter 显式声明：

required-mcp:
  - github           # 必需
  - filesystem       # 必需

optional-mcp:
  - linear           # 可选，有则用

加载 Skill 时检查 MCP 可用性，不可用时给出清晰提示。

5.3 Skill + MCP 的工作流​

第六章：Plugin 架构​

6.1 三位一体​

完整的 AI 应用能力 = Skills + MCP + Sub-agents：

6.2 决策树：何时用哪个​

新需求 →
  是否需要原子操作（读写文件、API 调用）？
    是 → 加 Tool 或 MCP Server
    否 →
      是否是可复用的任务模板？
        是 → 加 Skill
        否 →
          是否需要独立上下文/并行？
            是 → 加 Sub-agent
            否 → 直接 Prompt 处理

6.3 真实案例：Coding Agent 的 Plugin 架构​

Cursor / Claude Code 的 Plugin 层（典型配置）

MCP Servers:
  - filesystem          # 文件读写
  - github              # PR/Issue 操作
  - shell               # 命令执行
  - browser             # 网页查看
  - postgres            # 数据库查询

Skills:
  - create-component
  - refactor-rename
  - add-feature
  - fix-bug
  - write-tests
  - migrate-framework
  - pr-review
  - debug-issue

Sub-agents:
  - test-runner         # 隔离测试环境
  - documentation       # 写文档（不污染主对话）
  - exploration         # 大范围搜索（用完即丢）

6.4 配置文件​

主流工具的 Plugin 配置位置：

// Claude Code: .claude/
.claude/
├── settings.json
├── skills/
│   ├── pr-review/
│   │   └── SKILL.md
│   └── create-component/
│       └── SKILL.md
└── mcp.json              // MCP Server 配置

// Cursor: .cursor/
.cursor/
├── rules/                // Cursor 的 Rules（类似 Skills）
│   ├── coding-style.mdc
│   └── pr-review.mdc
└── mcp.json

第七章：团队级 Skills 治理​

7.1 Skills 的层级​

类似 CLAUDE.md（详见 6-9），Skills 也分层：

层级位置内容是否提交
全局~/.claude/skills/个人通用 SkillN/A
项目&lt;repo>/.claude/skills/团队共享 Skill提交 Git
模块&lt;repo>/&lt;module>/.claude/skills/模块特殊 Skill提交 Git
本地&lt;repo>/.claude/skills.local/个人项目偏好不提交

7.2 Skills Marketplace​

Anthropic 在推动 Skills 生态：

  • 官方仓库：anthropics/skills
  • 社区分享：可以发布、订阅、版本化

团队内部可以建私有 marketplace：

# 私有 Skills 仓库结构
team-skills/
├── README.md
├── skills/
│   ├── pr-review/
│   ├── create-component/
│   └── deploy-staging/
├── CHANGELOG.md
└── package.json    # 版本元数据

通过 npm/git submodule 引用：

// .claude/settings.json
{
  "skills": {
    "sources": [
      "./skills",
      "github:my-team/team-skills"
    ]
  }
}

7.3 PR 流程​

修改团队 Skill 应该走 PR：

## Skill 修改 PR 模板

### 改动说明
- 新增 / 修改 / 删除了哪个 Skill
- 关键变化

### 影响评估
- 哪些任务流程会受影响
- 是否破坏现有用法

### 验证
- [ ] 用 5 个真实场景测试新 Skill
- [ ] description 触发判断准确
- [ ] 已通知团队

7.4 Skill 度量​

度量 Skill 是否真的有用：

interface SkillMetrics {
  name: string;
  triggerCount: number;        // 被触发次数
  successRate: number;         // 完成任务的比例
  avgDuration: number;         // 平均执行时长
  userFeedback: {
    positive: number;
    negative: number;
  };
  topFailureReasons: string[]; // 失败 case 归因
}

// 长期低使用率 + 高失败率的 Skill 应该重写或下架

第八章：踩坑与最佳实践​

8.1 常见错误​

错误表现解决
Description 太泛各种请求都触发加正反向场景说明
Skill 太大一个 Skill 5000 字拆成多个 Skill
Skill 太小一个 Skill 50 字合并到任务级
互相冲突多个 Skill 都说"用于 X"明确区分场景
不写反例LLM 误用 Skill"不要用于..." 必须有
步骤太抽象"审查代码质量"具体到可执行
没有验证完成判定不清必须有"完成清单"
硬编码路径写死 /Users/xxx用相对路径或变量
缺少错误处理Skill 中途失败没有降级步骤里写"如果 X 失败则..."

8.2 优秀 Skill 的特征​

  • 一句话能说明白用途（description 简洁）
  • 用户用日常语言能触发（不靠技术黑话）
  • 5 分钟内能学会编辑（结构清晰）
  • 有反例（防止误激活）
  • 有验证清单（"完成"标准明确）
  • 可被其他 Skill 引用（组合性）

8.3 个人 Skills 库建议​

工作 1-2 周后，回顾哪些任务是高频重复的：

  • 每周做 3 次以上 → 值得封装
  • 步骤超过 3 步 → 值得封装
  • 容易出错的部分 → 值得封装

逐步建立 5-15 个核心 Skill，覆盖 80% 日常工作。

8.4 团队 Skills 库建议​

  • 从 1-2 个核心 Skill 起步：不要一上来建 50 个
  • 每个 Skill 都有 owner：负责维护更新
  • 季度审查：废弃低使用率的、合并相似的
  • 新人 onboarding：必读核心 Skills 列表

第九章：和 Cursor Rules、Copilot Instructions 的关系​

9.1 各家命名对照​

AnthropicCursorCopilot性质
CLAUDE.md.cursorrulescopilot-instructions.md项目规则（始终生效）
SkillsRules + .mdcCustom Instructions任务模板（按需触发）
MCPMCP（兼容）无原生工具协议
Sub-agent无原生无原生委派机制

9.2 Cursor Rules 的工作方式​

Cursor 的 .mdc 文件类似 SKILL.md：

---
description: When user asks to create a new component
globs: src/components/**
---

# Component Creation Rule

Always follow these steps when creating a component...

globs 字段是 Cursor 特有的，根据文件路径触发，比纯 description 触发更可靠。

9.3 跨工具的最佳实践​

如果团队同时用多个工具：

  • CLAUDE.md / .cursorrules：写共享的项目规则（编码规范、目录结构）
  • Skills（Anthropic）/ Rules（Cursor）：各自维护，但内容可互相参考
  • MCP：可跨工具复用（标准协议）

不要追求"一份配置走天下"——不同工具的能力差异很大，强行统一反而都用不好。

权威资料​

核对日期：2026-05-09